Developer CD Series 1998 November: Tool Chest

home *** CD-ROM | disk | FTP | other *** search

/ Developer CD Series 1998 November: Tool Chest / Dev.CD Nov 98 TC.toast / Tool Chest / Development Kits / MPW etc. / Debuggers / SADE / SADE 1.4a3 / sade.help < prev next >

Wrap

Text File | 1992-07-10 | 103.8 KB | 2,998 lines | [TEXT/sade]

SADE 1.4 Help Summaries Help summaries are available for each of the SADE commands. To see the list of commands enter "Help Commands". In addition, brief descriptions of Variables, Constants, Expressions, built in functions, and Shortcuts are also included. To see Help summaries, Enter a command such as Help Builtins # a list of builtin (predefined) variables and functions Help commandName # information about commandName Help Commands # a list of commands Help Expressions # summary of expressions Help Patterns # summary of patterns (regular expressions) Help Shortcuts # summary of SADE shortcuts Help Variables # summary of variable references Help Basetypes # summary of basic types recognized by SADE Copyright Apple Computer, Inc. 1987-1992 All rights reserved. - Builtins Functions AddrToSource # tries to display source for a particular code address Concat # concatenate strings Confirm # confirmation dialog Copy # extract a substring from a string Eval # evaluate the contents of a string Find # find pattern in memory Length # length of a string NaN # SANE NaN (Not a Number) Request # request dialog returning string SizeOf # size of a value or type SourceToAddr # tries to give code address for a point in a source file Timer # "tick count" timer with conversion to minutes,seconds,hundreths TypeOf # type (name) of a value Undef # is a value undefined? Where # symbolic representation of an address Variables Arg[n] # n'th parameter to current Proc or Func ActiveWindow # string with pathname of topmost SADE window Date # string with current date in the form dd-mmm-yy DisAsmFormat # string controlling format of DisAsm command output Exception # number of last exception raised Inf # SANE infinity NArgs # number of actual parameters to current Proc or Func ProcessId # id of current process being debugged (an integer) TargetWindow # string with pathname of the SADE window below the topmost one Time # string with current time in the form hh:mm:ss WorksheetWindow # string with pathname of SADE Worksheet window - Commands Abort Execute OnEntry SourcePath AddMenu Find Open Stack Alert For Printf Step Beep Func Proc Stop Begin Go Protect Target Break Heap Quit Trace Case Help Redirect Unbreak Close If Repeat Undefine Cycle Kill Resource Unprotect Define Leave Return Untrace DeleteMenu List SADEKey Version Directory Loop Save While Disasm Macro Shutdown WindowSize Dump MoveWindow SizeWindow Functions AddrToSource Eval Request Timer Concat Find Selection TypeOf Confirm Length SizeOf Undef Copy Nan SourceToAddr Where - Expressions The operators listed below are used in expressions in command parameters. (…) grouping @ address of † trap expression ^ pointer to . variable reference qualifier - unary negation ~ bitwise ones complement ! NOT ¬ logical NOT (¬ is Option-L) * multiplication / DIV ÷ division (÷ is Option-/) // MOD remainder + addition - subtraction << shift left >> shift right = == equal <> != ≠ not equal (≠ is Option-=) < less than <= ≤ less than or equal (≤ is Option-<) > greater than >= ≥ greater than or equal (≥ is Option->) & AND bitwise AND && logical AND XOR EOR bitwise exclusive OR | OR bitwise OR || logical OR := size compatible assignment <- arbitrary assignment Alternate spellings of several operators are provided. All of the operators are evaluated from left to right. Operators with the highest precedence are listed first, and operators in the same group have equal precedence. - Patterns - Patterns specify characters to be matched. Patterns may only be used from the Find… command in the Find menu. /entireRE/ regular expression - search forward \entireRE\ regular expression - search backward entireRE •RE regular expression at beginning of line (Option-8) RE∞ regular expression at end of line (Option-5) RE regular expression RE simpleExpr simple regular expression - defined below 'string' literal - no characters within '…' are special "string" literal - only \, ∂, {, and ` are special within '…' RE1RE2 regular expression RE1 followed by RE2 simpleExpr (RE) regular expression grouping charExpr single character regular expression - defined below simpleExpr* simple expression zero or more times simpleExpr+ simple expression one of more times simpleExpr«n» simple expression n times (Option-\, Option-Shift-\) simpleExpr«n,» simple expression at least n times simpleExpr«n1,n2» simple expression at least n1, at most n2 times charExpr character character (unless it has special meaning) ∂character character - defeats any special meaning (Option-D) ? any character except Return ≈ zero or more characters, except Return (Option-X) [charList] any character in the list [¬charList] any character not in the list (Option-L) charList ] ] first in the list represents itself - - first in the list represents itself character character charList character list of characters character-character character range (e.g. A-Z) - ShortCuts The following is a list of SADE shortcuts: Double click select word Triple click select line Double clicking before any quote (', ", or `) will select until the matching quote Double clicking before or after {}[]() will select until the matching character UpArrow move selection point one line above current selection DownArrow move selection point one line below current selection RightArrow move selection point one character to the right LeftArrow move selection point one character to the left CMD-Shift-UpArrow select text from current selection point to top of screen CMD-Shift-DownArrow select text from current selection point to bottom of screen CMD-Opt-UpArrow move selection point to top of file CMD-Opt-DownArrow move selection point to bottom of file CMD-DownArrow move selection point down to bottom of screen CMD-RightArrow move selection point to right edge of current line CMD-UpArrow move selection point to top of screen CMD-LeftArrow move selection point to left edge of current line CMD-Backspace delete from current selection to end of file In Dialogs without an Edittext item Y Yes N No CMD . Cancel - Variables VARIABLE REFERENCES There are three different types of variables -- program variables, debugger variables, and system variables. Program variables are defined in your program; debugger variables are defined during your debugging session; and system variables represent objects in the Macintosh runtime environment (e.g., registers, low-memory globals, and ROM locations). When SADE looks up a simple symbol name, it is first looked up as a debugger symbol, then as a program symbol, and finally as a system symbol. Thus, if the same name is used as a debugger symbol and as a program symbol the debugger symbol will be returned. In order to resolve such potential name conflicts SADE supports two escape characters, which may preceed an identifier to indicate whether the identifier is a program or system symbol: ` (backquote) identifies a symbol as a program symbol Δ (option j) identifies a symbol as a system symbol PROGRAM VARIABLES The simplest form of program variable reference is just the name of the variable itself. A simple reference (a single identifier) is looked up in the current name scope (CNS) as defined by where execution has stopped in the program. If execution has stopped in a particular procedure, then the variables of that procedure and the global variables in the compilation unit of that procedure will be accessible via simple references. If you need to reference a variable which is outside of the current name scope (i.e., not in the procedure where execution has been suspended or not one of the globals in the compilation unit of that procedure) then a fully qualified reference is needed. A fully qualified reference is very much like a complete file pathname describing how to get to the variable from a particular compilation unit. The syntax is: \unit [.procedure]* .variable where \ indicates that a unit name follows. In Pascal this will be the name on the UNIT or PROGRAM statement; in C or assembly this will be the name of the compilation unit's file (with ∂'s used to escape any characters not normally allowed in identifiers). The [.procedure]* indicates zero or more procedure names (more than one for nested procedures) separated by dots. This will identify the path to a variable when it is not in the current CNS. DEBUGGER VARIABLES Debugger variables are defined with the DEFINE command. These variables can be used to save values from the user program, to control debugger language contructs, etc. Debugger variables are untyped, that is, they take on the type of the value that is assigned to them (which may change the next time they are assigned to). The format of the define command is: Define [global] {declaration [':=' initialization]},… where "declaration" is a variable name followed by an optional dimension specification in square brackets, and "initialization" is a simple expression in the case of a scalar variable, or, an parenthesized list of expressions (separated by commas) in the case of an array variable. A list of values for an array may include items of the form "n of v" where "n" is an expression specifying a count and "v" is an expression specifying a particular value. Any number of variables may be declared in a single DEFINE command. The DEFINE command is not allowed inside of conditional or looping constructs. Arrays/Scalars: Scalar variables hold a value of any type. An array variable will hold up to its specified dimension of values of any type; these values may be heterogeneous, that is, they need not be of the same type. Scope: Variables which are defined outside of PROCs or FUNCs are global, and are accessible both inside and outside of PROCs. Variables which are defined inside of PROCs and FUNCs are local and have a lifetime limited to the particular activation of the PROC or FUNC, unless the optional "global" keyword was specified in the DEFINE command. - Basetypes The following basic types are recognized by SADE. They are grouped in order of increasing size or related category: Boolean # 1 byte Pascal boolean (bit 0 = 0 ==> false; 1 ==> true) UnsignedByte # Unsigned byte Byte # Signed byte Cchar # Character byte UnsignedWord # Unsigned word (2 bytes) UnsignedShort # Same as UnsignedWord Word # Signed word Short # Same as Word Integer # Same as Word Pchar # Pascal character word (low byte contains character) PascalChar # Same a Pchar UnsignedLong # Unsigned long (4 bytes) UnsignedInt # Same as UnsignedLong Long # Signed long Int # Same as long LongInt # Same as Long PString # Pascal variable length string CString # C null-terminated string AsIsString # As-is string (Packed array of char) Real # Floating point single precision (4 bytes) Float # Same as Real Single # Same as Single Double # Floating point double precision (8 bytes) Extended # Floating point extended precision (10 bytes) Extended12 # MC68881 floating point extended precision (12 bytes) Comp[utational] # Floating point computational integer (8 bytes) - Abort —stops execution of scripts Syntax Abort Description The Abort command terminates execution of the current script and returns you to SADE, canceling all pending commands. This means that if current execution is within a structured statement (Begin...End, for instance), or if multiple commands are selected, these pending commands are not executed. To terminate a break action without canceling pending commands, use the Stop command. Example The way in which keyDown and mouseDown events are handled by the EventFilter procedure in this example illustrates the difference between Abort and Stop. A keyDown event (in the context of this example) does not entail any additional action, so you can use Abort to terminate the break action and return to SADE immediately. In the case of a mouseDown event, however, the location of the mouse when the break occurs is important; therefore, you use Stop to terminate the break action so that the Printf command showing the location of the mouse is executed before SADE is reentered. #-- Establish target, suspending application #-- and reentering SADE at main.(1) Directory 'VolName:some:path:toProg:' Target 'MyProg' Break \MyProg.main.(1) #-- Break action examines the current event type #-- (assuming the event record is named myEvent). #-- For mouseDown, shows coordinates of mouseDown and stops #-- (quitting break action but executing rest of pending SADE commands) #-- For keyDown, aborts (quitting break action AND rest of commands). #-- For any other event, shows event type and continues executing #-- (by default, break actions end with an implicit Go command) Proc EventFilter Define global mouseAt; If myEvent.what = 1 then # mouseDown event mouseAt := myEvent.Where; Stop; elseif myEvent.what = 3 # keyDown event "keyDown"; Abort; else Printf "Event type %d: \n", myEvent.what; Printf; End End Begin Break _getNextEvent from applzone..applzone^ EventFilter Go Printf "Mouse down at H: %d\n V: %d\n", mouseAt.h, mouseAt.v; End #-- output Event type 0: Event type 8: Event type 6: Mouse down at H: 208 V: 144 #-- With same break action in place, restart target. Go #-- output Event type 6: keyDown See also Break, Stop - AddMenu —creates a menu or adds menu items Syntax AddMenu [ menuName [ itemName [ command ] ] ] Description The AddMenu command lets you create menus and add menu items to execute SADE commands. The parameters menuName, itemName, and command are all string expressions; if they are string constants, you must enclose them in quotation marks. If a menu of menuName does not exist in the menu bar, a new menu is created. If a menu item with the specified itemName already exists, it is replaced; otherwise, a new menu item is created. You can include a keyboard equivalent for the item by listing the key after a slash (/) at the end of the string. See the “Examples” section. (Warning: Be careful not to inadvertently specify a keyboard equivalent that is already defined for a different menu item, because the new definition will replace the existing one without any warning.) The command specifies a string that is executed when a user clicks on itemName. It can be a SADE command (see the first example), or something more complex, such as the name of a procedure that you have defined (see the second example). If you do not specify itemName or command, AddMenu returns the current value from the specified level down. For instance, if you specify itemName without any commands, AddMenu displays the command that’s currently defined for that menu item. If you omit menuName, itemName, and commandName as well, SADE returns the current values for all user-defined menus and menu items. Example 1 #-- Create a menu called Debug with two items, Disasm and Code #-- Disasm disassembles instructions starting at the end of the last #-- disassembly. Code Resources displays information about code resources. #-- Note that you can invoke Disasm from the keyboard with Command-4. AddMenu 'Debug' 'Disasm/4' 'Disasm' AddMenu 'Debug' 'Code Resources' 'Heap restype "CODE"' Example 2 #-- Define a procedure called ShowWhere and then create a menu item, #-- Statement Selected Is?, which executes this procedure. ShowWhere shows what #-- routine a selected statement belongs to; if there isn't sufficient symbol #-- information, ShowWhere displays an error message explaining why it cannot #-- show the routine name. Proc ShowWhere Define loc := SourceToAddr(ActiveWindow, 1) If typeOf(loc) = 'PString' then Alert Concat('Cannot determine address from source: ', loc) else Alert Concat('At ', Where(loc)) End End AddMenu 'SourceCmds' 'Statement Selected Is?' 'ShowWhere' See also DeleteMenu - AddrToSource —displays source statement corresponding to address Syntax AddrToSource (address [, Boolean ] ) Description AddrToSource displays and selects the source statement corresponding to the specified address. If the source file isn’t already open, it is displayed as a read-only window. If the source file is already open as a read/write window, AddrToSource changes the window to read-only. If you omit the optional Boolean value or specify 0 (FALSE), SADE displays the source window behind the front most window (most likely the window from which you executed AddrToSource). If you specify a nonzero value for Boolean (TRUE), SADE brings up the window as the front most window. AddrToSource returns a Boolean value indicating whether it was able to display the source statement (TRUE) or not (FALSE). See also SourceToAddr - Alert —displays an alert box Syntax Alert [ Beep ] message Description The Alert command displays an alert box containing the specified message. The alert box is displayed until you click the OK button. Message is a string expression; if it is a string constant, it must be enclosed in quotation marks. If beep is specified, a sound is generated when the alert box appears. Example If length(str) > 64 then Alert "string longer than expected" End See also Beep - Beep —generates tones Syntax Beep [ note [,duration [,level ] ] ... ] Description The Beep command produces each given note for the specified duration and sound level. You must separate each note specification (that is each note and its optional duration and level) from the next note by blank spaces or tabs. If you do not specify note, SADE produces a standard Macintosh warning beep of predetermined pitch and duration. Note can be one of the following: • A number indicating the count field for the square wave generator, as described in the Sound Driver chapter of Inside Macintosh, Volume II • A string in the format [n ] letter [ # | b ], where n is an optional number indicating the octaves below or above middle C, followed by a letter indicating the note (A–G) and an optional sharp (#) or flat (b) character. Duration is specified in sixtieths of a second. The default duration is 15 (one-quarter second). Level specifies the magnitude of the sound. Your parameter can be a number from 0 to 255. The default level is 128. Example Beep '2C,20,75 2C#,40,150 -1D,60,75' #-- Play the three notes specified: C, C sharp, and D, for one-third, #-- two-thirds, and one full second, respectively. The middle note is #-- twice as loud as the other notes. C and C sharp are two octaves #-- above middle C. D is one octave below. See also Alert - Begin ...End —groups commands Syntax Begin commands End Description The Begin...End construct allows you to group together or bracket a sequence of commands. You can use this construct to specify a break action consisting of multiple commands or procedure calls. Example 1 #-- This example specifies a conditional break action that depends on the #-- value of the pointer theStr^. Break DisplayString.(4) Begin str := theStr^ # save value of parameter in variable str If str = '***' then Stop End End Example 2 #-- This example shows how to use the Begin…End construct to nest Step commands. Step onEntry Begin Printf "gStopped is %d\n",gStopped Printf "newStopped is %d\n",newStopped Step onEntry Begin Printf "gStopped is %d\n",gStopped Printf "newStopped is %d\n",newStopped End End - Break —sets breakpoints Syntax Break addr ,... [ breakAction ] or Break trap [ from addrRange ] ,... [ breakAction ] or Break trapRange [ from addrRange ] ,... [ breakAction ] or Break all traps [ from addrRange ] [ breakAction ] Description The Break command sets one or more breakpoints in a target program’s code. There are two types of breakpoints: address breakpoints and trap breakpoints. You can follow either kind of breakpoint by a break action, that is, a command (or series of commands) that is executed when the breakpoint is reached. Addr specifies a RAM address or symbolic reference. If you use a symbolic reference, the code need not be in memory when you set the breakpoint. Trap specifies a trap name or number. You must prefix a trap number with the trap character (†, or Option-T) and a trap name with an underscore character (_InitGraf, for example). TrapRange specifies a range of traps. You must use the range operator (..) between trap names or numbers. BreakAction Specifies a command or series of commands that is executed when the breakpoint is reached. From addrRange indicates that a break is to occur only when the trap is called from the specified range. All traps sets a breakpoint on every trap. You can set trap breakpoints on a single trap, a range of traps, or on all traps. In each case you can also specify a memory range so that SADE breaks only when the trap is called from the specified range. If you want to specify the same trap in multiple Break commands, use the List command to see what breakpoints have been set. When implementing trap breakpoints, SADE first looks for a Toolbox or Operating System call that matches a specified trap name, checking the address range if one was given. If no match is found, SADE then looks for trap ranges containing the trap. SADE takes the most recently defined range containing the trap, again checking the address range if one was specified. Note: If you set an address breakpoint on a trap call for which a trap breakpoint has already been set, the address breakpoint is recognized and the trap breakpoint is not. If you have specified a break action, SADE resumes program execution after executing your break-action commands. There are two ways to suspend program execution as part of a break action. The Abort command returns control to SADE immediately, canceling any pending commands. The Stop command executes any pending commands and then returns control to SADE. Warning: SADE saves the commands you specify in the break action and does not interpret them until reaching the breakpoint. Symbol references that may appear to be correct when you define the break action may be out of scope when the action is actually executed. So make sure that program symbol references are correctly interpreted at the time the breakpoint is reached. Do not delete the breakpoint as part of a break action. SADE stores the break action with the breakpoint; if you remove the breakpoint, you throw away the break action as well — even though SADE is in the middle of executing it — so the action does not execute properly. Note: If no break action is specified and the execution command (Go, for instance) just prior to hitting a breakpoint is part of a structured statement (such as While...End), or if multiple commands were selected, the remaining commands are executed after hitting the breakpoint and re-entering SADE. You can specify multiple breakpoints, separated by commas, with a single Break command. If this command includes a break action at the end, the action is applied to all breaks in the list. Examples #-- This example shows breaks set on different traps, trap ranges, and traps called #-- from particular memory ranges. Break _GetResource Break †$A997..†$A9A0 Break all traps from myproc.(1)..myproc.(5) Break all traps from applZone..applZone^ #-- The following example sets multiple breakpoints. Break procB.(1), _LineTo from procA.(1)..procA.(1000), _setPort Begin; "hit one"; end List break procB.(1) # $586398 # processID =5 # has break action _LineTo # processID =5 # †$A891 # called from procA.(1) .. procA.(83) # has break action _SetPort # processID =5 # †$A873 # has break action #-- A break set on top of a matching breakpoint replaces the older one. Breakpoints match #-- if they are set on the same address or trap and the called from address range, if there #-- is one, matches. Break DoMenuCommand.(0) Break _LineTo List Break Trap _SetPort (†$A873) Trap _LineTo (†$A891) DoMenuCommand.(0) See also Abort, List, Stop, Trace, Unbreak - Case —changes case sensitivity Syntax Case on | off Description This command turns case sensitivity on and off. By default, case sensitivity is on, which means that when looking up symbols, SADE first performs a case-sensitive lookup. If the symbol isn’t found, SADE converts all the characters to uppercase and looks again. When case sensitivity is off, SADE converts all symbols to uppercase before any lookup, speeding up the search process. Because symbols in C are case sensitive, C programmers must have case sensitivity turned on or SADE will not recognize any of the symbols in the program (except those that are all uppercase). Pascal programmers, however, may want to set case sensitivity off to speed up performance. Note however, that even with case set to on, SADE will find Pascal symbols (no matter what combination of uppercase and lowercase characters you enter) because if SADE cannot find a symbol in a case-sensitive search, it performs a second search after converting all characters to uppercase. Examples #-- These examples illustrate how Case on and Case off work by showing #-- the output you get when typing symbols in different combinations of lowercase and #-- uppercase letters. #-- C programmers Case on CFunction #-- output CFunction.(0) CFUNCTION #-- output ### Could not find "CFUNCTION" as a program symbol cfunction #-- output ### Could not find "cfunction" as a program symbol Case off CFunction #-- output ### Could not find "CFunction" as a program symbol #-- Pascal programmers Case on PascalProc #-- output PASCALPROC.(0) PASCALPROC #-- output PASCALPROC.(0) Case off PascalProc #-- output PASCALPROC.(0) - Close —closes a file Syntax Close [ all | windowName ] Description The Close command closes the specified file or all files. WindowName is the name of the window (file) to close. It is a string expression and you must enclose it in quotation marks if it’s a string constant. Specifying all closes all of the open windows open in SADE. If you don’t specify any parameters, Close closes the target window. Note, however, that the SADE Worksheet file cannot be closed. If the contents of a file have not been saved, a dialog box asks whether they should be. Examples Close 'myFile' Close targetWindow #no quotes needed--uses SADE variable targetWindow - Concat —concatenates strings Syntax Concat ( [ string,…] ) Description Concat returns the concatenation of the specified string expressions. If you supply nonstring arguments, Concat tries to coerce them to strings. If you specify no arguments, Concat returns a null string. Example pathName := 'root:examples:' fileName := 'sample.c' Open Concat(pathName,fileName) # equivalent to open 'root:examples:sample.c' - Confirm —displays confirmation dialog box Syntax Confirm ( message [, Boolean ] ) Description Confirm presents a dialog box containing the specified message and either two or three buttons depending on the value you specify for Boolean. Confirm returns a number indicating the button that you press in the dialog box. If you omit the optional Boolean or specify 0, Confirm presents OK and Cancel buttons, and returns 1 or 0 respectively when you press them. If you specify a nonzero value for Boolean, Confirm presents Yes, No, and Cancel buttons, which return 1, 0, and –1 respectively when you press them. Example confirm('Are you sure?',1) See also Request - Copy —copies string Syntax Copy ( string, characterIndex, length ) Description Copy returns all or part of the specified string. Use characterIndex to indicate the first character to copy; for example, to start with the third character of the string, specify 3 (it’s 1-based). Use length to specify he length of the output string. Example #-- Strips the hard drive name off the directory path (because the #-- copy begins with the fifth character) and copies the rest of the #-- directory path to the pathName variable. You can then open a file #-- by concatenating pathName with a filename. This example specifies 255 #-- as a number for the length because it is large enough to accommodate #-- long pathnames. directoryPath := 'root:examples:cexamples:' pathName := copy(directoryPath,5,255) Open Concat(pathName,'sample.c') - Cycle —continues execution within construct Syntax Cycle [ if Boolean ] Description The Cycle command causes execution to continue from the conditional test of a While, Repeat, or For construct, or from the beginning of a Loop construct. If a Boolean expression is specified, Cycle executes only if the Boolean expression (Boolean) evaluates to nonzero; otherwise execution continues immediately following the Cycle command. Example Define testNum := 0 Define endNum := 6 Define cycleMax := 4 Repeat Printf "testNum = %d\n", testNum testNum := testNum + 1 Cycle If testNum < cycleMax "\nDidn't cycle" Until testNum = endNum #-- output testNum = 0 testNum = 1 testNum = 2 testNum = 3 Didn't cycle testNum = 4 Didn't cycle testNum = 5 Didn't cycle See also Leave - Define —declares a SADE variable Syntax Define [ global ] declaration [,...] where declaration has the form name [ [dimension] [ := initValue | = initValue ] ] Description The Define command defines one or more SADE variables. You must define a variable before using it. The variable declaration identifies the name, scope, and (optionally) the initial value of the variable. Separate multiple declarations by commas. The name of the variable must be unique in the current scope unless you declare it global. The dimension is the size of the array if it is a structured variable. It is an expression enclosed in brackets. The initValue is an expression for the initial value of simple types, or for structured types a list of the following form: ( [ expr of ] initValue , ..) where the optional of clause allows for replication of a value. SADE variables are dynamically typed; that is, their type is determined on assignment (and may be changed by new assignments). SADE variables defined as arrays require an index. SADE array variables may contain a heterogeneous set of values; that is, the elements may contain values of different types. An initial value for simple types may optionally be specified by an expr following the assignment operator (:=) or, in this case only, (=). If the declared item is an array, a list of initial values may be specified as the values of the array elements. The scope of a variable can be either global or local. If a variable is defined outside a procedure (or function), its scope is automatically global. In other words, it is known both inside and outside of any procedures. If a variable is declared inside a procedure, its scope is local unless you specify the global option. If a global and a local variable exist with the same name, the local symbol overrides the global symbol. Redefining global variables replaces the previous definition, with one exception: If the definition is within a procedure, and the new definition matches the existing definition, then the existing definition is retained. For example, when a global variable is defined within a procedure or function and is given an initial value, the initialization occurs only when the variable is actually created. Subsequent invocations of the procedure do not affect the current value of the global variable, and can make use of the value left in the variable by the preceding invocation. You cannot use the Define command within any structured statement. To remove a variable definition, use the Undefine command. Examples #-- Define a five element array, with the first four elements true and the last #-- element false. Define global test[5] := (4 of 1,0) #-- Define a 30 element array, with the first 29 elements true and the last #-- element false. Define arraysize := 30 Define myArray[arraysize] := (arraysize-1 of 1,0) #-- In the next example, note that the definition of index in RotateLeftOneWCarry() #-- is local to that procedure; otherwise it would be attempting to redefine the #-- global index that's used as a For loop counter when RotateLeftOneWCarry() #-- is called. Proc RotateLeftOneWCarry() Define global SADEArray[4] := ("indexed by one", 2, 3.33, "fourth and last") Define index Define holder For index := 1 to 4 do If index = 1 then holder := SADEArray[index] else SADEArray[index-1] := SADEArray[index] If index = 4 then SADEArray[index] := holder End End End End Define index Define holder For index := 1 to 4 do RotateLeftOneWCarry() For holder := 1 to 4 do SADEArray[holder] End Printf "\n" End Undefine RotateLeftOneWCarry #-- output 2 3.33 fourth and last indexed by one 3.33 fourth and last indexed by one 2 fourth and last indexed by one 2 3.33 indexed by one 2 3.33 fourth and last See also Undefine - DeleteMenu —deletes menus or menu items Syntax Deletemenu [ menuName [ itemName ] ] Description The DeleteMenu command deletes menus and menu items. MenuName specifies the name of a user-defined bar menu. If you specify menuName but do not specify itemName, SADE deletes the entire menu. Because menuName is a string expression, you must enclose it in quotation marks if it is a string constant. ItemName is an item in the bar menu that you specified with menuName. It is a string expression and you must enclose it in quotation marks if it is a string constant. You cannot delete the standard SADE menus and menu items (the Apple, File, Edit, Find, Mark, and Window menus). Warning: If you omit both menuName and itemName, SADE deletes all user-defined menus, that is, the SourceCmds and Variables menus (which are defined by commands in the SADEStartup file) and any menus that you have added in the SADEUserStartup file. You can restore these menus by executing SADEStartup and SADEUserStartup. Example Deletemenu "Special" "Launchapp" See also AddMenu - Directory —sets or writes the default directory Syntax Directory [ directoryName ] Description The Directory command sets the default directory for all SADE file-oriented operations to the specified directory. If you don’t specify directoryName SADE displays the current default directory. DirectoryName follows the same conventions as MPW, that is, you can specify a full or partial pathname. It is a string expression and you must enclose it in quotation marks if it is a string constant. If a directory specification contains a colon but does not begin the with a colon, SADE reads it as a complete pathname. Examples #-- Change the current directory of HD:MPW to HD:MPW:Examples Directory 'Examples' #-- Change the current directory of HD:MPW to HD:MPW:Examples:CExamples. #-- You can still specify a partial pathname, but you must precede the directory #-- name with a colon. Directory ':Examples:CExamples' #-- Define a macro for your work directory Macro here "'HD:MPW:Example:CExample'" Directory here See also Sourcepath - Disasm —disassembles code Syntax Disasm [ addr [ count ] ] or Disasm [ addrRange ] Description The Disasm command disassembles instructions starting at the location specified by addr or addrRange . The default behavior when no address is specified is to begin disassembling at the end of the last disassembly. If the value of the program counter has changed since the last disassembly, the program counter (PC) is used as the default starting address. If no range or count is specified, the number of instructions (not lines) disassembled defaults to 20. AddrRange specifies the range of addresses for the disassembly. You specify a starting and ending address separated by the range operator (..). See “Examples”. Each line of the disassembly output is divided into three fields: the address of the instruction, the hexadecimal encoding for the instruction, and the assembly code (opcode, operand, and comment). You can modify the presence, order, and format of these fields by changing the value of the built-in variable DisAsmFormat. The disassembly output also correlates source statement numbers with the assembly code instructions (see the second example). Examples #-- Disassemble five instructions in standard format, starting at the fourth #-- statement of the AdjustMenus routine. Disasm $23B5EE 5 #-- output AdjustMenus.(4) 0023B5EE 2F0B MOVE.L A3,-(A7) 0023B5F0 7004 MOVEQ #$04,D0 0023B5F2 3F00 MOVE.W D0,-(A7) 0023B5F4 A939 _EnableItem ; A939 0023B5F6 6008 BRA.S AdjustMenus.(6) ; 0023B600 #-- Disassemble the instructions between the first and fourth statements of the #-- AdjustMenus routine. Disasm AdjustMenus.(1)..AdjustMenus.(4) #--output AdjustMenus.(1) 0023B5D2 598F SUBQ.L #$4,A7 0023B5D4 A924 _FrontWindow ; A924 0023B5D6 285F MOVEA.L (A7)+,A4 AdjustMenus.(2) 0023B5D8 598F SUBQ.L #$4,A7 0023B5DA 3F3C 0081 MOVE.W #$0081,-(A7) 0023B5DE A949 _GetMHandle ; A949 0023B5E0 265F MOVEA.L (A7)+,A3 AdjustMenus.(3) 0023B5E2 2F0C MOVE.L A4,-(A7) 0023B5E4 4EBA 02FC JSR IsDAWindow.(0) ; 0023B8E2 0023B5E8 4A00 TST.B D0 0023B5EA 588F ADDQ.L #$4,A7 0023B5EC 670A BEQ.S AdjustMenus.(5) ; 0023B5F8 AdjustMenus.(4) 0023B5EE 2F0B MOVE.L A3,-(A7) 0023B5F0 7004 MOVEQ #$04,D0 0023B5F2 3F00 MOVE.W D0,-(A7) 0023B5F4 A939 _EnableItem ; A939 See also Dump - Dump —displays memory Syntax Dump [ byte | word | long ] [ addr [ count ] ] or Dump [ byte | word | long ] [ addrRange ] Description The Dump command displays memory at the location specified by addr or addrRange. If no parameter is given, the memory starting at the program counter is displayed. The memory is displayed in hexadecimal and ASCII characters according to the specified format, which may be byte, word (two bytes), or long (four bytes). The default format is word. Count specifies the number of bytes to dump. The default, if you do not specify a count, is 16 bytes. AddrRange specifies the range of addresses for the dump. You specify a starting and ending address separated by the range operator (..). See “Examples”. Remember that to dump the value of a variable myVar, you must specify Dump @myVar (since Dump myVar would take myVar’s value and use it as an address). Examples #-- Dump 16 bytes (the default if no count is specified) from the A5 register. Dump byte A5 #-- output $00146A8E 00 14 68 74 FF FF FF FF 00 00 00 00 00 00 00 00 ..ht........ #-- Dump 40 bytes from the A5 register and group the output in words. Dump word A5 40 #-- output $00146A8E 0014 6874 FFFF FFFF 0000 0000 0000 0000 ..ht............ $00146A9E 000E 6C66 0000 FFFF FFFF FFFF FFFF FFFF ..lf............ $00146AAE 0001 4EF9 000E 6E00 ..N...n. #-- Dumps 40 bytes from the A5 register and group the output in long words. Dump long A5..A5+40 #-- output $00146A8E 00146874 FFFFFFFF 00000000 00000000 ..ht............ $00146A9E 000E6C66 0000FFFF FFFFFFFF FFFFFFFF ..lf............ $00146AAE 00014EF9 000E6E00 00 ..N...n.. See also Disasm - Eval —evaluates string as an expression Syntax Eval (text, [ message ] ) Description Eval evaluates the text of a string argument as an expression. The function result can be any type, depending on what the expression evaluates to. You can optionally supply a message; if an error occurs, Eval returns this message as the function result. If you do not supply a message and an error occurs, Eval aborts and reports the error. Example #-- Pass the name of a program variable (menuId) to a variable in SADE (theVar). #-- SADE uses the Printf command to print the name of the variable and Printf #-- with Eval to print its value. If SADE cannot determine the value of the program #-- variable (for example, because it is out of scope), Printf prints ??? (the #-- message part of Eval). theVar := menuId Printf "%t = %t\n", theVar, Eval(Concat('`', theVar), '???') #-- Note that this example uses Concat with the backquote character (`) to treat #-- theVar as a program symbol. The code in this example is similar to code in the #-- SADEStartup file that implements the Show Value menu item. - Execute —executes commands in a file Syntax Execute filename Description The Execute command executes the commands and definitions contained in the specified file. The Execute command can’t be used within a structured statement. Filename is the name of the file to execute. It is a string expression and must be enclosed in quotation marks if it’s a string constant. Example #--In this example, the Redirect command creates a file to hold output from SADE. #-- Entering a string echoes the string. That output is redirected to the file, #-- becoming the file’s contents. Here the string is a comment and a SADE command #-- to execute the contents of the next file in the chain. Open 'exec1' Redirect 'exec1' '"\n executing exec1 now"' "execute 'exec2'" Open "exec2" Redirect 'exec2' "'now executing exec2'" "execute 'exec3'" Open "exec3" Redirect 'exec3' '"Done in exec3"' Redirect pop all Execute "exec1" Alert "Try a tile windows here\n∂ Then look at the worksheet for output" #-- output executing exec1 now now executing exec2 Done in exec3 - Find —searches for a target Syntax Find [ count ] pattern [ ,n ] [ addrRange [ mask mask ] ] or Find [ count ] pattern [ ,n ] [ addr [ count ] [ mask mask ] ] or Find [ same [ addrRange ] | [ addr [ count ] ] ] Description The Find command searches memory for a specified pattern, which can be either a numeric or string expression. If you specify the count keyword, Find tells you how many occurrences of the target it found. If you omit the count keyword, Find displays the address of the first occurrence of the pattern. You can use the n parameter to specify which occurrence of the pattern you want; for instance, if you specify 3 for n, Find returns the address of the third occurrence of the pattern. If the keyword count is specified, Find returns the number of occurrences of the target string it has found. If you omit it, Find displays the address of the first occurrence of the target string. An integer n indicates which occurrence of the target pattern you want; for example, if you specify 3, SADE displays the address of the third occurrence of the pattern. Note that you must precede this number with a comma. AddrRange is the address range in which to limit the search. If you do not specify a range of addresses (or a starting address), the search range is the MultiFinder block containing the application’s heap and stack (in other words, all of the memory that belongs to the application). Addr is an address at which to begin the search. You can also specify count, the number of bytes to search beyond the specified address; otherwise the search goes from the starting address to the end of memory. If you do not specify a starting address or range of addresses, the search range is the MultiFinder block containing the application’s heap and stack (in other words, all of the memory that belongs to the application). The mask parameter (prefaces by the mask keyword) is an optional numeric or string expression that is logically ANDed with the contents of each memory location before the search comparison is done. The same keyword instructs Find to search for the next occurrence of the same target pattern as specified in the last Find command. You can optionally specify a different address range or starting address and number of bytes for the search. If you used the count keyword in the previous Find command, you cannot use same in the next one; if you do so, SADE returns a message that the pattern cannot be found. Important: Remember that expression values in SADE are long words by default; to specify another size, use typecasting, as shown below. Examples Dump $20 $40 $00000020 0027 A002 0027 A00A 0040 1F52 0027 A012 .'...'...@.R.'.. $00000030 0027 A01A 0027 A032 0040 113C 0027 A02A .'...'.2.@.<.'.* $00000040 0040 113C 0040 113C 0040 113C 0040 113C .@.<.@.<.@.<.@.< $00000050 0040 113C 0040 113C 0040 113C 0040 113C .@.<.@.<.@.<.@.< #-- Search $40 bytes for the number of occurrences of the string, $113C, #-- starting at address $20. The string has been cast to word size; otherwise #-- the default search would be for a long word and nothing in the range #-- matches $0000113C. The search finds nine occurrences of the string. Find COUNT (word)$113C $20 $40 9 #-- Search the range $20 to $96 for the string $113C and display the address #-- of the first occurrence of this string. The search string has been typecast #-- to word size using C style casting. Find (word)$113C $20..$96 $0000003A #-- Search $40 bytes beginning at address $20 for the string $113C and display #-- the address of the second occurrence of this string. The search string has #-- been typecast to word size using Pascal style casting. Find word($113C), 2 $20 $40 $00000042 #-- Search the range $20 to $96 for the string $0000113C and display the address #-- of the first occurrence of this string. A mask has been used Find $0000113C $20..$96 MASK $0000ffff $00000038 #-- Find the same target string as the last example, except the memory #-- range has been changed. Find SAME $40..$50 $00000040 - For ...End —loops with a control variable Syntax For clause [ do ] commands End where clause may have one of the following forms: var := expr to expr var := expr downto expr var := expr , ... Description The For...End construct provides looping with a control variable. The enclosed commands are executed until the control variable has taken on each successive value in the range expressed by clause. You must declare the control variable var before using it, and you cannot specify an array variable. For the clause expr to expr, the commands are executed and the control value (var) is incremented once for each integer value in the range. For the clause expr downto expr, the control value is decremented. The third clause is a list of expressions; the commands are executed until the control variable has taken on the value of each of the listed expressions. You can nest For...End constructs; you may also use them within other flow- control constructs, as well as in break actions. The control variable may be modified within the body of the loop (but cannot, of course, be shared between nested constructs). Example Define var := 0 Define outerLooper, syncopation For outerLooper := 3 downto 1 do "\n" For syncopation := "one","two","three", var Printf "%d -- " , outerLooper syncopation var := var + 1 End End #-- output 3 -- one 3 -- two 3 -- three 3 -- 0 2 -- one 2 -- two 2 -- three 2 -- 4 1 -- one 1 -- two 1 -- three 1 -- 8 - Func ...End —defines a SADE function Syntax Func name [ ( argName ,... ) ] commands End Description SADE functions are delimited by the Func...End construct. The last statement to be executed must be a Return command specifying a return value. The type of a function is not specified in the definition but rather takes on the type of the value returned. (Thus functions are not limited to returning results of a single type.) SADE functions use conventional calling notation, with the function name followed by a list of parameters enclosed by parentheses. Function parameters are handled in the same fashion as procedure parameters, and the predefined SADE variables Arg and NArgs may be used. (See the description of the Proc command for an example using these variables.) User-defined functions may be called anywhere an expression is allowed. Example #-- This function factors a number and displays the total. Func fact(n) If n <= 1.0 then Return 1.0 else Return n * fact(n-1) End End See also Proc, Return - Go —resumes execution Syntax Go [ til addr ,...] [ onEntry commands ] Description The Go command resumes program execution at the current program counter. If you specify the keyword til, SADE sets a temporary breakpoint at the specified address(es). When the breakpoint is encountered, SADE is reentered and the breakpoint is removed. Note that if you specify multiple breakpoints with the keyword til, SADE removes all breakpoints when any of them is reached. If the address is in ROM, SADE informs you that it can’t set a breakpoint in ROM. Use onEntry to specify an action to occur when SADE is reentered following resumption of the program—for example, to display the value of a variable. If you do not use onEntry but execute the Go command as part of a group of commands (in a script file or highlighted in the Worksheet) SADE evaluates the other commands first before executing Go regardless of the order in which you place the commands in the script or in the Worksheet. Important: You cannot execute a Step command following Go in a script or as part of a highlighted group of commands unless you use the onEntry keyword. With onEntry you can tell SADE to execute a Step command after returning to SADE following the Go command. (See the last example.) Examples #-- The first example resumes operation of the program and breaks at #-- \OtherCompilationUnit.myProc.(1). Go til \OtherCompilationUnit.myProc.(1) #-- Assume that the program is suspended and a breakpoint has been set within the #-- procedure that initializes the values of the variables gstopped and newstopped. #-- The following code fragment resumes program execution, stops at the breakpoint, #-- and displays the values of gstopped and newstopped. Go onEntry Begin Printf "gStopped is %d\n",gStopped Printf "newStopped is %d\n",newStopped end See also Step, Stop - Heap —displays, checks or totals heap information Syntax Heap [ display ] [ addr ] [ blocktype ] Heap check [ addr ] Heap totals [ addr ] [ blocktype ] Heap Display Description The Heap command displays information about the specified heap. Display is the default if you don’t specify any options, so you can omit it if you wish. Addr specifies the beginning address of a heap. If you omit this parameter, Heap displays information about the heap pointed to by the global variable theZone. By default, the following information is displayed: • a dot if the object is locked or nonrelocatable • the address of the beginning of the block and the block length • the block type: H=relocatable, P=nonrelocatable, F=free • the address of the master pointer if it’s a relocatable block • block attributes (Flags): L=locked, R=resource, P=purgeable • for standard toolbox data structures, a description of the structure • for a resource, the resource type and ID, the reference number of the file it’s in, and the resource name You can specify one of the following blocktypes to limit the display to a particular type of block: • purge[able] - limits the display to purgeable blocks. • nonreloc[atable] - limits the display to nonrelocatable blocks. • reloc[atable] - limits the display to relocatable blocks. • free - limits the display to free blocks. • lock[ed] - limits the display to locked blocks. • res[ource] - limits the display to resources. • restype 'type' - limits the display to the specified resource type. Note that the resource type is case-sensitive and you must enclose it in single quotation marks ('MENU', for example). Example #-- Display heap information for 'MENU' type resources. Heap restype 'MENU' #-- output BlkAddr BlkLength Typ MasterPtr Flags RType RId RFRef RName $00316590 $00000098 H $0031452C R MENU 1000 $0584 "File" $00316838 $00000050 H $00314528 R MENU 1001 $0584 "Edit" $00316888 $000000F4 H $00314524 R MENU 1002 $0584 "Log" Heap Check Description The Heap check command checks the consistency of the current application heap, which is by default the heap referenced by the global variable theZone. If you specify addr -the address of another heap zone- it must be the address of the heap zone header (you can’t check part of a heap). Heap check performs range checking to make sure all pointers are even and non-NIL, and that block sizes are within the range of the heap. It verifies that the self-relative handle points to a master pointer referring to the same block. For nonrelocatable blocks, it checks if the heap zone pointer points to the zone where the block exists. Heap check also verifies that the total amount of free space is equal to the amount specified in the header, and that all pointers in the free master pointer list are in the heap. Examples #-- This example intersperses Printf commands with Heap check commands to show at #-- which memory locations the heap is okay. Printf "Checking %P's heap at $%.08X\n", ^Pstring( $910)^, TheZone Heap check TheZone Printf "Checking the System heap at $%.08x\n", SysZone Heap check SysZone Printf "Checking the MultiFinder heap at $%.8x\n", **$2a6+$c Heap check $2a6^^+$c #-- output Checking SADE's heap at $00146EF2 The heap is okay. Checking the System heap at $00001400 The heap is okay. Checking the MultiFinder heap at $00023d64 The heap is okay. Heap Totals Description The Heap totals command summarizes the state of the current application heap, which is by default the heap referenced by the global variable theZone. You can specify another heap that starts at addr, the beginning address of a heap. Information is given for free, nonrelocatable, and relocatable objects. If you wish to restrict the display to a particular type of block, use the blocktype parameter. You can specify one of the following blocktypes to limit the display to a particular type of block: • purge[able] - limits the display to purgeable blocks. • nonreloc[atable] - limits the display to nonrelocatable blocks. • reloc[atable] - limits the display to relocatable blocks. • free - limits the display to free blocks. • lock[ed] - limits the display to locked blocks. • res[ource] - limits the display to resources. • restype 'type' - limits the display to the specified resource type. Note that type is case-sensitive and you must enclose it in single quotation marks ('MENU', for example). Example Heap totals #-- output Total Blks Total Size Free 23 49080 Nonrelocatable 7 1348 Relocatable 89 21232 Locked & NonPurgeable 2 5796 Locked & Purgeable 2 8136 UnLocked & Purgeable 6 680 UnLocked & NonPurgeable 79 6620 Heap (total) 119 71660 - Help —displays help information Syntax Help [ identifier ,… ] Description The Help command displays information about using SADE, including the syntax of all SADE commands. To see what values identifier can have, just enter Help. - If ...End —conditionally executes commands Syntax If Boolean [ then ] commands [ elseif Boolean [ then ] commands ] ... [ else commands ] End Description The If...End construct allows for conditional execution of sequences of SADE commands. Each If must be concluded by a corresponding End. Although elseif and else are optional, they must appear between the If and End in the order indicated in the syntax description. You can use more than one elseif but at most one else. The commands controlled by an If extend to the corresponding End, or to the first corresponding elseif or else. The commands controlled by an elseif extend to the next corresponding elseif, else, or end. The commands controlled by an else extend to the corresponding End. When an If...End construct is evaluated, if the If Boolean is true, the statements controlled by the If are executed and the remainder of the construct to the End keyword is skipped. If the Boolean is false, the statements controlled by the If are skipped and the next (elseif) condition is checked, if present. If an elseif condition is evaluated and is true, the commands it controls are executed and the remainder of the construct is skipped. If no conditions are evaluated as true, when the else command is reached (if present), the commands controlled by the else are executed (otherwise, they’re skipped). You can nest If...End constructs. Example #-- Step through a five element array using a low to high index, looking for #-- the first true element, and resetting it to false. The first four elements #-- are true and the last one is false. Define global Test[5] := (4 of 1,0) Proc IfDemo Define WhichTest Define ShowMe For WhichTest:= 1 to 5 do Printf "\n" For ShowMe:= 1 to 5 do Printf "%t", test[showMe] End Printf " - " if Test[1] "Test[1] true" elseif Test[2] "Test[2] true" elseif Test[3] "Test[3] true" elseif Test[4] "Test[4] true" elseif Test[5] "Test[5] true" else "all tests false" End Test[ShowMe] := 0 End End IfDemo #-- output 11110 - test[1] true 01110 - test[2] true 00110 - test[3] true 00010 - test[4] true 00000 - all tests false #-- This example shows a SADE procedure that steps until the menuItem variable #-- is false. Proc StepWhile If menuItem = 1 Step onEntry StepWhile Else Stop End End Step onEntry StepWhile - Kill —terminates an application Syntax Kill [ filename ] Description If you want to terminate an application, (whether it’s suspended or not), use the Kill command. Be aware, though, that Kill is dangerous, since it doesn't give the unlucky application a chance to perform its usual exit routines (like saving data). Kill does perform cleanup activities like freeing the MultiFinder memory occupied by the application and removing its trap patches. Filename specifies the name of the application or tool to terminate. It is a string expression and you must enclose it in quotation marks if it’s a string constant. The filename parameter is optional; if you omit it, SADE simply terminates the current target application. If you are debugging an MPW Tool, the MPW Shell, not the tool itself, is SADE’s target. Therefore, if you want to kill a tool that is targeted but leave MPW running, you cannot use the Kill command. For this purpose, SADE provides a procedure named KillTool; that suspends the execution of a tool but leaves MPW running. The KillTool procedure is defined in the SADEStartup script, so it is always available. To use the procedure, simply execute the command KillTool from the Worksheet window. You can also kill a tool but leave MPW running by choosing the Kill menu command from the File menu. If a tool is being debugged when the Kill menu item is chosen, SADE calls KillTool. Examples #-- Terminate execution of the current target. Kill #-- Define a variable, ExPath that specifies the path to the Sample application. Kill #-- terminates Sample by using Concat to concatenate the directory path with the #-- application name. Define ExPath := "Volume1:CExamples:" Kill Concat(ExPath, "Sample") - Leave —exits from a looping construct Syntax Leave [ if Boolean ] Description The Leave command lets you exit from a Loop, While, Repeat, or For construct. You can specify a condition for leaving with the if parameter. If the expression specified by Boolean evaluates to true, then you exit the loop, otherwise continue to repeat the commands in the loop. Example #-- Increment the variable testNum each time through the loop. Exit the loop #-- when testNum reaches 3. Define testNum := 0 Repeat Printf "testNum = %d\n", TestNum Leave if testNum = 3 testNum := testNum + 1 Until testNum = 6 Printf "after leaving Repeat loop - testNum = %d\n", testNum #-- output testNum = 0 testNum = 1 testNum = 2 testNum = 3 after leaving Repeat loop - testNum = 3 See also Cycle, For, Loop, Repeat, While - Length —returns length of a string Syntax Length ( string ) Description Length returns the length in bytes of the specified string. See also SizeOf - List —lists processes, tracepoints, breakpoints, and protected addresses Syntax List process or List trace [ traps | addrs ] or List break [ traps | addrs ] or List protect Description The List command may be used to display the active processes, breakpoints, tracepoints or protected memory addresses. For processes, the display includes the following information: a process number, a creator, and the filename for the process. For breakpoints and tracepoints, List displays the location along with its symbolic representation. The optional traps or addrs keywords limit the display to trap or address breakpoints (or tracepoints) respectively. List protect displays the addresses that are currently write protected. Refer to the Protect command for further explanation of this option. Examples #-- List the breakpoints that have been set and the active processes. List break # list all breakpoints set #-- output EVENTLOOP.(5) <has break action> EVENTLOOP.(11) EVENTLOOP.(2) List Process #-- output Process#, creator, FileName 2, 'MACS', 'Finder' 3, 'MSWD', 'Microsoft Word' 4, 'sade', 'Sade' 5, 'MPNT', 'MacPaint' s 7, '????', 'Sample1' #-- Lists the current protected addresses List Protect #-- output $0107F390 .. $0107F393 (from target code only) $0107F3A0 .. $0107F3A3 (from any code) See also Trace, Break, Protect - Loop ...End —repeats commands until Leave Syntax Loop commands End Description The Loop...End construct provides unconditional looping. The enclosed commands are executed repeatedly. To exit the loop, use the Leave command. You can nest Loop constructs. Example Define Inner := 0 Define Outer := 0 Loop Loop Inner := Inner + 1 Printf "Inner: %d " , Inner Leave if Inner > Outer End Inner := 0 Outer := Outer + 1 printf "Outer: %d\n", Outer leave if Outer > 4 End #-- output Inner: 1 Outer: 1 Inner: 1 Inner: 2 Outer: 2 Inner: 1 Inner: 2 Inner: 3 Outer: 3 Inner: 1 Inner: 2 Inner: 3 Inner: 4 Outer: 4 Inner: 1 Inner: 2 Inner: 3 Inner: 4 Inner: 5 Outer: 5 See also Leave - Macro —defines a macro Syntax Macro name string-expr Description The Macro command associates a string of characters with a name. Macros allow you to define short, familiar names to use instead of long, unfamiliar strings. For instance, the SADEStartup file defines macros that let you use MacsBug-like syntax for certain SADE commands. String-expr specifies the string of characters to associate with the macro. You must enclose it in quotation marks. If you specify a string constant (such as a directory name) you must enclose it in two sets of quotation marks. Macro definitions can be nested; that is, they can contain references to other macros. Macro definitions cannot be recursive, however; in other words, a macro definition can’t reference itself. Macro definitions are not allowed in structured statements. Macros may be redefined. Macro definitions are limited to a length of 254 characters. Examples Macro br 'break' Macro clr 'Unbreak all' Macro dir "'volume:very:long:directory:path'" directory dir - MoveWindow —moves window to location Syntax MoveWindow [ to h,v ] [window ] Description Moves the upper-left corner of the specified window to the specified location. The coordinates (0,0) are located at the left side of the screen at the bottom of the menu bar. If the location specified would place the window’s title bar entirely off the visible screen, an error is returned. If you do not specify a window SADE assumes the target window (the second window from the front). If you do not specify a location, SADE returns the window’s location without any effect on the window. The keyword To is followed by the horizontal and vertical coordinates (in pixels) of the new location in that order. They are nonnegative integers. Separate them by a comma. Examples #-- Move the target window’s upper-left corner to a point approximately one inch #-- in from the upper-left corner of the screen, and one inch below the bottom of #-- the menu bar. (There are about 72 pixels per inch on the Macintosh display #-- screen.) MoveWindow to 72, 72 #-- The next example returns the location of the target window, which would be #-- 72, 72 when executed after the command in the first example. MoveWindow # output- # MOVEWINDOW 72 72 See also SizeWindow, WindowSize - NaN —not a number Syntax NaN ( expression ) Description NaN converts the specified expression into a SANE 10-byte extended value. - OnEntry —sets commands for SADE entry Syntax OnEntry [ exception-action ] Description The OnEntry command supplies commands that are to be executed each time SADE is entered. Each OnEntry command replaces the commands specified by the previous OnEntry command. In the SADEStartup file, the StandardEntry procedure is specified as an OnEntry exception action. You can define your own OnEntry actions in the SADEUserStartup file, but you’ll probably want to use the one in SADEStartup as a model (so as not to lose the operations it performs). Because the OnEntry command accepts only one command or procedure invocation, if you want to execute multiple commands and/or procedures upon entry, use the Begin..End construct to group them. See also Break, Begin - Open —opens a file Syntax Open [ source ] [ behind ] filename Description The Open command opens the specified file. Specifying source opens the file as read-only. If this option is omitted, the window is opened as a read-write window. Specifying behind opens the window behind the front most SADE window; otherwise, it’s opened as the front most window. If the file is in the current directory, you can specify the name only; otherwise, specify a complete or partial directory name as well as the filename. The file must be of type 'TEXT' or SADE will be unable to open it. Filename is a string expression and must be enclosed in quotation marks if it’s a string constant. Example Open source 'myFile' See also Close, Save - Printf —prints formatted output Syntax Printf [ format [ , argument ] … ] or Printf [ ( format [ , argument ] … ) ] Description The Printf command prints string characters to a SADE window or file. You can also use Printf to convert values—for example, convert decimal characters to hexadecimal—and to specify how the output appears. Format is a string containing characters to print, as well as format specifications for arguments that follow. Format specifications are preceded by the % character. For instance, to print the value of the variable myVar as a decimal number along with a message (assuming its value is 5), enter: Printf "The value of myVar is %d", myVar #-- output The value of myVar is 5 Remember that the format specification is a string so you must enclose it, including the percent sign, in quotation marks. Argument is the value to be printed; it can be an actual numeric value or a variable whose value you want to print. Each format specification applies to zero or more arguments. When the format specifications are exhausted, any remaining arguments are ignored. Likewise, when the specified arguments are exhausted, any remaining format specifications are ignored. Examples #-- Displays record definition of system type EventRecord. #-- Notice how EventRecord.Where, which is of type Point, has been #-- expanded to show its definition too. Printf "%P", ^pstring($910)^ myProg Printf "%P", *(pstring*) $910 myProg Printf "%-t", EventRecord RECORD WHAT: Word; MESSAGE: Long; WHEN: Long; WHERE: RECORD CASE Word OF (1): (RECORD V: Word; H: Word; END); (2): (RECORD VH: ARRAY [(0, 1)] OF Word; END); END; MODIFIERS: Word; END #-- Doing the same thing with a target program variable #-- of type EventRecord. The %t format specifier lets #-- the Printf display format be controlled by the #-- type of the variable displayed. typeof(myEvent) EVENTRECORD Printf "%t", myEvent RECORD WHAT: 3; MESSAGE: 16686; WHEN: 284053; WHERE: RECORD CASE Word OF (1): (RECORD V: 272; H: 267; END) (- - -); END; MODIFIERS: 2432; END - Proc ...End —defines a SADE procedure Syntax Proc name [ argName ,... ] commands End or Proc name [ ( argName ,... ) ] commands End Description SADE procedures are delimited by the Proc...End construct. The procedure name is followed by an optional parameter list; if present, the list identifies parameters by name only. Parameters are not assigned a type but instead take on the types of the actual parameter values when the procedure is called. You can enclose the parameter list in parentheses if you wish, but if you do so, you must also use parentheses when calling the procedure (and vice versa). When you call a procedure, the number of actual parameters that you pass need not match the number of formal parameters in the procedure definition. If you pass fewer parameters than the number of formal parameters, SADE assigns a special undefined value to the formal parameters for which there are no corresponding actual parameters. If you pass more actual parameters than there are formal parameters, SADE ignores the extra parameters unless you use the predefined SADE variables Arg and Nargs in your procedure definition. Arg is an array variable that has the form Arg[n] where n is the nth actual parameter passed when the procedure is called. Nargs contains the number of actual parameters. These two predefined variables enable you to write flexible procedures when you don’t know how many parameters will actually be passed when the procedure is called. Two of the examples show a simple for loop that uses Arg and Nargs to set multiple break points. Note that the values of these variables represent the parameter state of the currently active procedure and are not defined outside of it. You must define a procedure before making a call to it. Therefore, if you want mutually recursive procedures, you must first define a “dummy” procedure (similar to a Pascal FORWARD definition). You can then write a second procedure that calls the dummy procedure, and then redefine the dummy procedure to do what you want (including calling the second procedure). The minimal dummy procedure definition is: Proc foo; End;. You can nest procedure calls. Examples #-- This example illustrates the use of the Nargs and Arg variables to write a #-- procedure that will accept an indefinite number of parameters. When you call #-- this procedure, it sets a breakpoint on each parameter that you pass. Nargs #-- contains the number of the last parameter passed; Arg is used like an array #-- variable to accesses each parameter by number. Therefore, the loop is in effect #-- for the first through the last parameter passed, and each parameter is passed #-- in turn to the Break command by way of the count and arg variables. Proc SetBreaks () Define count For count := 1 to Nargs Break Arg[count] End End #-- Call SetBreaks to set breakpoints on DrawWindow, EventLoop, SetLight SetBreaks (DrawWindow, EventLoop, SetLight) See also Func - Protect —write protect memory addresses Syntax Protect [from target | all] <address expression> [<number of bytes>] Description Protecting a region of memory causes SADE to detect any writes to that region and report them. When the exception is reported, the contents of the protected memory will have been changed. Use Protect from target if you wish to have SADE report memory writes when the program counter is within the application's heap zone. This is the default. Use Protect from all when you wish SADE to report memory writes, regardless of the location of the program counter at the time of the write. This is the more dangerous option and should be used with EXTREME CAUTION! <address expression> is any expression which SADE can evaluate as an address, e.g. '&foo', '$1C48D0A', 'EVENTS.MAINEVENTLOOP.(3)', etc. <number of bytes> is an optional value specifying how many bytes to protect beginning at that address. The default value for <number of bytes> is 4. Examples #-- EXAMPLE #1 #-- A program which defines an n-element array in C and tries to write to #-- element[n] of that array. Here, int1 would change instead of the last #-- element of myArray[], as the programmer probably intended. main () { int myArray[5] = {10, 20, 30, 40, 50}; int int1 = 1200; int int2 = 1400; ... myArray [5] = int2; /* fault here, int1 should change */ } #-- To determine the location of the write to int1, protect &int1: protect &int1 #-- SADE responds with the following confirmation: Protect 4 byte(s) at $00EF753C (from target code only) #-- You may also verify for yourself which addresses have been protected list protect $00EF753C .. $00EF753F (from target code only) #-- Execute the program. The write protection fault will occur and SADE will #-- suspend the program at (or just after) the instruction which caused the error: Write to protected memory detected at main.(4) #-- You may now remove the protection by either killing the target or executing: unprotect all #-- EXAMPLE #2 #-- You can protect code as well as data. To protect a function called 'DoUpdate' #-- which is followed by another function 'DoActivate', use protect DoUpdate DoActivate - DoUpdate #-- EXAMPLE #3 #-- For a stack sniffer which is 100% guaranteed (unlike the VBL-based OS routine), #-- protect the address in ApplLimit. protect ApplLimit #-- EXAMPLE #4 #-- SADE's sizeof function is handy for specifying a byte count, e.g. to protect #-- variable 'foo' use protect &foo sizeof(foo) See also Unprotect, List Protect - Quit —quits SADE Syntax Quit Description The Quit command terminates SADE and passes control to another process as determined by MultiFinder. Be aware that Quit kills any suspended applications. See also Shutdown - Redirect —redirects output Syntax Redirect [ append ] filename or Redirect [ pop ] [ all ] Description The Redirect command redirects the output from SADE commands to the specified file. The append parameter instructs SADE to append output to the end of the specified file rather than replacing the contents of the file. You can also use the § character (Option-6) to replace or append to the selection in an open window see the example below). You can nest Redirect commands to as many as 10 different files; SADE maintains the names of these files as a last-in, first-out queue. If you use the pop keyword, or if you use no parameters at all, the output from SADE commands is redirected to the file at the head of the queue. If you specify all or pop all, standard output is redirected to the current command window. Warning: Be aware that if you use use Redirect to replace the contents of a file that’s not open, there’s no way to undo it. (If the file is open, you can close it and respond “No” when the dialog asks whether to save changes.) Note: Any error conditions cause SADE to perform an implicit pop all for any redirected files; this ensures that output returns to the current command window. Examples #-- Redirects output to the current selection in the file whyNot. Redirect "whyNot.§" #-- Create a file to hold output from SADE. Entering a string echoes the string. #-- That output is redirected to the file, becoming the file's contents. Here the #-- string is a comment and a SADE command to execute the contents of the next #-- file in the chain. Open 'exec1' Redirect 'exec1' '"\n executing exec1 now"' "Execute 'exec2'" Open "exec2" Redirect 'exec2' "'Now executing exec2'" "Execute 'exec3'" Open "exec3" Redirect 'exec3' '"Done in exec3"' Redirect pop all Execute "exec1" Alert "Try a tile windows here\n∂ Then look at the worksheet for output" #-- output Executing exec1 now Now executing exec2 Done in exec3 - Repeat ...Until —conditionally repeats commands Syntax Repeat commands Until Boolean Description The Repeat...Until construct provides conditional looping with a test at the end of the loop. The enclosed commands are executed until Boolean is true. The enclosed commands are executed at least once. Repeat constructs may be nested. Example Define count := 0 Repeat Printf "%d\n", count count := count + 1 Until count = 5 #-- output 0 1 2 3 4 See also Leave - Request —displays request dialog box Syntax Request ( string [, string ] ) Description Request returns a string after displaying a request dialog box. The dialog presents an OK button and a Cancel button. The first string argument appears in the dialog box as the request message. The second, optional string argument specifies a default string to present in the request box. When you click Cancel, Request returns the string "_CANCEL_" . Otherwise, it returns the string that you enter in the box. Example Request('Choose a name','Homer') See also Confirm - Resource —displays the resource map Syntax Resource [ display ] [ addr ] [ restype 'type ' ] or Resource check [ addr ] Description The Resource command displays the contents of your application’s resource maps and the system resource map. If you want to display only a particular map, addr should be the address of the map. The information displayed for each map includes: its location, the resource ID, the resource type, the value of the master pointer, whether the resource is locked or unlocked, and the resource name. If a resource isn’t loaded, the master pointer field shows “NotLoaded.” The default, if you don’t specify any options, is to display the resource maps, so you can omit the display option if you wish. You can also restrict the display to a particular resource type by using the restype keyword with the desired type. Note that type is case-sensitive and should be enclosed in single quotation marks ('WIND', for example). The Resource check command checks the target application’s resource maps for consistency. If you want to check a particular map, addr should point to the address of the map. If an inconsistency is found, the command displays a diagnostic message specifying the problem. Example Resource restype 'MENU' #-- output Resource Map at $00501E8C ResId RType MasterPtr Locked? Name 128 MENU $00501E8C Unlocked 129 MENU $00501EC0 Unlocked 130 MENU $00501F50 Unlocked 131 MENU $00501FA0 Unlocked Resource Map at $0010CF68 ResId RType MasterPtr Locked? Name 33024 MENU NotLoaded 49046 MENU $0010EC94 Unlocked 49047 MENU $001683F8 Unlocked 49063 MENU $000DF76C Unlocked 49064 MENU $0010E764 Unlocked 49065 MENU $0010E794 Unlocked 61536 MENU NotLoaded - Return —returns from a procedure or function Syntax Return [ result ] Description The Return command returns you from a procedure or function currently in execution. When returning from a function, the function result must be specified. (When returning from a procedure, there is no return value.) Result is an expression that specifies the return value. Example Define global SadeArray[4] := (1, "this is two", 3.3, 4) Func MiscTypes (index) Return SadeArray[index] End Define selector For selector := 1 to 4 do Printf "%t \n", MiscTypes(selector) End #-- output 1 this is two 3.3 4 See also Func, Proc - SADEKey —defines a key for entering SADE Syntax Sadekey [ keycode ] Description The SADEKey command lets you specify a different Command-Option key combination for entering SADE. To see what key is specified as the SADEKey, just type SADEKey. A complete list of keycodes can be found in the Toolbox Event Manager chapter of Inside Macintosh Volume V. Example sadekey $33 #-- define Command-Option-Delete combination as SADEKey - Save —saves a file Syntax Save [ all | filename ] Description The Save command saves the specified file or, if all is specified, saves all files. If the specified file wasn’t modified since the last time it was saved, Save does nothing. If no parameters are given, Save saves the target window. Filename is a string expression and you must enclose it in quotation marks if it’s a string constant. Example Save 'myFile' See also Open, Close - Selection —returns text of current selection Syntax Selection ( windowName ) Description Selection returns the text of the current selection in the specified window. The value returned is of type PString. To get the value of the string if it contains a name or expression (for instance, to set a breakpoint), apply the Eval function on the string. Example #-- Return the string that is highlighted in the active window, that is, the #-- frontmost window. Selection (ActiveWindow) See also Eval - Shutdown —shuts down or restarts the machine Syntax Shutdown [ restart ] Description The Shutdown command terminates SADE and calls the Shutdown Manager. Be aware that all unsaved work is lost. Specifying restart will restart the Macintosh after shutting down. - SizeOf —returns size of variable, type, or argument Syntax SizeOf ( variable | type | argument ) Description SizeOf returns the number of bytes occupied by a variable or type. You can also use SizeOf to determine the size of an argument to a SADE procedure or function. You cannot use SizeOf with SADE array variables. Example #-- This example shows the size of the SADE type, Long. SizeOf(long) #-- output 4 See also Length - SizeWindow —sets a window’s size Syntax SizeWindow [ to h,v ] [window ] Description SizeWindow sets the size of the specified window to the specified horizontal and vertical dimensions. If the size specified would cause the window to be too big for the screen, SADE returns an error message. Window is the name of the window to size. If you do not specify a window, SADE uses the target window (second from the front). The keyword To is followed by the horizontal and vertical dimensions (in pixels) of the window in that order. They are nonnegative integers. Separate them by a comma. Examples #-- Make the target window 200 pixels square in size. Note that a there are #-- about 72 pixels per inch on the Macintosh display screen. SizeWindow To 200, 200 #-- Display the size of the sample.c window: SizeWindow 'sample.c' #-- output SIZEWINDOW 630 393 sample.c #-- Make the Worksheet window 500 x 100 pixels in size. Note the use of #-- the built-in Concat function to concatenate the directory path defined #-- by sadedir with the name of the SADE Worksheet. SizeWindow To 500, 100 Concat(sadedir,'SADE Worksheet') See also MoveWindow, WindowSize - SourcePath —tells SADE where your source files are Syntax Sourcepath [ [ add | del[ete ] ] directoryName , ... ] Description The SourcePath command tells SADE what directory your source files are in. If your source files are in more than one directory, you can give the SourcePath command a list. The a list of directory names must be separated by commas. If you’re unsure which directories you’ve specified, simply enter Sourcepath and the current search path is displayed. Specifying the add parameter will add a directory to the list of directories in the search path. Specifying del[ete] deletes a directory from the list of directories in the search path. Warning: If you specify a directory without using the add keyword, any directories previously specified are replaced. Examples Sourcepath 'srcdir', ':otherdir' # sources in more than one directory Sourcepath add ":samples" # add directory Samples to search path See also Directory - SourceToAddr —returns address of source statement Syntax SourceToAddr ( windowName [, errorFlag ] ) Description SourceToAddr returns the address corresponding to the statement selected in the specified window. The window need not be active. SourceToAddr displays the address symbolically; SourceToAddr returns zero if it cannot determine the address. If you pass a nonzero value in the optional errorFlag, SourceToAddr returns a string describing why the address could not be found. Example #-- SourceToAddr returns the address of the statement that a user has highlighted #-- in the target (source code) window. If the user has highlighted code that #-- does not represent a statement, that is, if SourceToAddr returns a Pstring, #-- then SADE returns an error to the user. Note that this code is similar to code #-- in the SADEStartup file that implements the Statement Selected Is? item in the #-- SourceCmds menu. foo := SourceToAddr(targetWindow,1) If TypeOf(foo) = 'PString' then #report error in foo else #foo has address See also AddrToSource - Stack —displays stack frames Syntax Stack [ count ] [ at addr ] Description The Stack command displays a list of the stack frames for the target application. The stack frames displayed are based on register A6 or addr if at is specified. For each entry, Stack gives the address of the stack frame, the name of the procedure or function that allocated the frame, and the name and offset (if available) of the parent procedure. The count parameter is the maximum number of stack frames to display counting back from the current frame). Example Stack at DisplayText.(6) Stack Frame Addr Frame Owner Called From <main> %__MAIN $0032BC24 main %__MAIN+$0028 $0032BB2C SkelMain main.(51) $0032BB0C LogEvent SkelMain.(13)+$0012 $0032BADC ReportUpdate LogEvent.(50)+$0004 $0032BACC DisplayText ReportUpdate.(1)+$0004 - Step —executes single step Syntax Step [ asm | line ] [ into ] [ onEntry commands ] Description The Step command lets you execute your program one step at a time, from either the source code level or the object code level. Specify line to perform source-level debugging. This is the default, so you can omit this option if you wish. Specify into to step into subroutines. The default, if you omit this parameter, is to step over subroutines. Specify asm to perform object-code (assembly-language) debugging. The default, if you omit this parameter, is source-level debugging. If you specify asm, execution proceeds one instruction at a time; the instruction at the program counter is executed and SADE is re-entered. SADE always treats traps as single instructions; SADE steps over them, stopping at the first instruction following the trap. You can either step into or over subroutines called by JSR and BSR instructions. If you specify into, SADE steps in, stopping at the first instruction of the subroutine. If you omit into, SADE treats BSR (branch to subroutine) and JSR (jump to subroutine) instructions as single instructions. The onEntry commands option is used to specify actions to occur upon returning to SADE after stepping the program—for example, to display the value of a variable. This option is required if you want to execute more than one step at a time as part of a script or SADE procedure. If you do not use onEntry but execute the Step command as part of a group of commands (in a script file or highlighted in the Worksheet) SADE evaluates the other commands first before executing the Step command regardless of the order in which you place the commands in the script or in the Worksheet. This means, for example, if you place a command such as Printf after a Step command to display the value of a variable, and execute the commands together, Printf displays the value of the variable before, not after, the step. Important: You cannot execute more than one Step command at a time, whether as part of a script or as a highlighted group of commands unless you use the onEntry keyword. With onEntry you can tell SADE to execute another Step command after returning to SADE following the first step. Warning: Don’t try to step over a routine that does not return to the caller; for instance, a call to longjmp(). SADE steps over procedure and function calls by setting the trace bit until after the JSR or BSR is executed, and then replaces the return address with the address of a SADE routine. Since longjmp() restores a previously saved register set, including a new stack pointer, SADE’s return is lost. If you want to go to the routine restored by longjump0, execute Step asm into until the registers have been modified and then do a source step. Or better still, if you know where the jump will go, set a breakpoint in that routine. Examples #-- If these two commands are executed together, SADE displays the value of #-- newStopped before stepping the program (remember that SADE evaluates all #-- other commands in a script before executing a Step command). Step Printf "The value of newStopped is %d",newStopped #-- output - value of newStopped before step #-- Use the onEntry keyword to display the value of a variable after stepping. #-- Note in the second example that the Printf command is part of the Step command—it #-- belongs to the action specified by onEntry—so it must be on the same line as Step #-- or, as in this case, made part of the line by the continuation character (∂). Step onEntry ∂ Printf "The value of newStopped is %d",newStopped #-- output - value of newStopped after step #-- You can use the Begin..End construct to execute multiple commands as part of the #-- action specified by onEntry. This example displays the value of three different #-- variables after stepping. Step onEntry Begin Printf "The value of newStopped is %d\n",newStopped Printf "The value of gStopped is %d\n",gStopped Printf "The value of menuID is %d\n",menuID End #-- To step through a program using a script or a block of SADE commands, you #-- must use the onEntry command. The following procedure uses onEntry to step #-- a given number of times (in this case three times); the onEntry command tells #-- SADE what to do after each step. In this case, onEntry instructs SADE to #-- take another step. define StepCount proc __Step__ if (StepCount > 0) StepCount := StepCount - 1; step OnEntry __step__ end end proc StepN(__n__) StepCount := __n__ Step OnEntry __Step__ end StepN (3) # Step three times - Stop —terminate break action Syntax Stop Description The Stop command terminates the current break action and returns you to SADE. If the current execution was within a structured statement (Begin...End, for instance), or if multiple commands were selected, the pending commands are executed. To terminate a break action and cancel pending commands, use the Abort command. Example Directory 'VolName:Path:toMyProg:' Target 'myProg' Proc WhichEvent(stopType) Define global EventType[16] := ('null', 'mouse-down','mouse-up', 'key-down', 'key-up','auto-key', 'update', 'disk-inserted','activate', 'network', 'device driver', 'app1',' app2', 'app3', 'app4') If theEvent.what = stopType then Printf "%P received, stopping\n", EventType[stopType+1] Stop else EventType[theEvent.what+1] Printf End End Break _waitNextEvent from applzone..applzone^ whichEvent(1) Go #-- output key-down update key-down mouse-down received, stopping See also Abort, Break, Quit - Target —identify your application Syntax Target [ progName [ using symbolFileName ] [ onEntry commands ] ] Description The Target command tells SADE the name of the application you want to debug and identifies the symbol file (the .SYM file generated by the linker). Target also launches the application, stopping at the first line of the main program, and opens the source file containing main. To find out what the current target is, just type Target. To release the current target application (for example, if an application is targeted by SADE, you cannot relink it until you release it) use Target with a null string enclosed by double quotation marks, that is, Target "". progName is the name of the application to debug. Enclose it in quotation marks if it is a string constant. If you omit progName, SADE returns the name of the current target application. SymbolFileName is the name of the symbol file generated by the linker. Enclose it in quotation marks if it is a string constant. If the .SYM file is already in the same directory as the application and is called progName.SYM (which it usually is), you don't need to bother with the using option. The onEntry option is used to specify actions to occur upon returning to SADE after launching the program. Note: If you select the Stop Before Constructor menu command, SADE stops your program as soon as it is launched instead of bringing it to the first line of main. Examples #-- The first example specifies the MPW Shell as the target and uses the using #-- option to specify ToolStuff as the tool to debug. Note that the Target command #-- automatically opens the source file and breaks at main.(0). SourcePath add "VolName:MPW:ToolStuff:" Target "VolName:MPW:MPW Shell" using "VolName:MPW:ToolStuff:tool.sym" #-- Run tool to break to SADE with tool as target. #-- Target puts pc at main.(0) automatically #-- The Target command in this example puts a breakpoint in the DoMenuCommand #-- routine and runs the program to that point. Target 'sample1' onEntry Begin break DoMenuCommand Go End - Timer —returns timing values Syntax Timer ( [ value [, Boolean ]]) Description Timer uses the global variable TickCount to provide timing-related functions. If you pass no arguments, Timer returns the current TickCount. If you specify a value (typically a previous value of TickCount), Timer returns the difference between that value and the current value of TickCount (that is, TickCount–value). If you also specify a nonzero Boolean value, the difference is returned as a string of the form "sss.hh", representing seconds and hundredths of a second. (If the Boolean is zero, it’s ignored.) Example #-- Execute together the lines in the following example to see how long SADE #-- takes to launch your application. Define starttime := Timer() Target 'sample1' onentry Timer (starttime,1) - Trace —sets tracepoints Syntax Trace addr ,… or Trace trap [ from addrRange ] ,... or Trace trap-range [ from addrRange ] ,... or Trace all traps [ from addrRange ] Description The Trace command sets tracepoints on the specified address or traps within the target program. You can set tracepoints on a single trap, a range of traps, or on all traps. After setting the tracepoints, you can resume program execution. When the program encounters the tracepoint, SADE displays a message on standard output, reporting the address or trap being traced, with a symbolic representation of the address if possible. Program execution resumes after SADE displays the message. Addr is a RAM address or symbolic reference. If you use a symbolic reference, the code need not be in memory at the time you set the tracepoint. Trap is a trap name or number. You must prefix a trap number with the trap character (†—Option-t) and a trap name with an underscore character (_InitGraf, for example). Trap-range specifies a range of traps. Use the range operator (..) between trap names or numbers. If addrRange is specified, SADE displays the trace message only when the trap is called from the specified range. Specifying all traps sets a tracepoint on every trap. You can specify multiple tracepoints, separated by commas, with a single Trace command. To remove a tracepoint, use the Untrace command. Example #-- These two Trace commands set traces on a range of traps, in the first case #-- using trap names with the underscore character, and in the second case using #-- the trap operator with trap numbers. Trace _OpenResFile.._GetResource Trace †$A997..†$A9A0 See also Break, List, Untrace - TypeOf —return type of an expression Syntax TypeOf ( expression ) Description TypeOf returns a string containing the name of the type of the given expression. If SADE doesn’t know the name of the type, it returns a string of the form "Type #n ", where n is SADE’s internal index for the type. - Unbreak —removes breakpoints Syntax Unbreak addr ,... or Unbreak trap ,... or Unbreak trap-range ,... or Unbreak all [ traps | addrs ] Description The Unbreak command clears the breakpoint as well as any associated break action, for the specified addresses or traps. The all option clears all breaks set in the target program. The all option can also be followed by traps or addrs to restrict the command to traps or addresses respectively. Addr is a RAM address or symbolic reference. Trap is a trap name or number. You must prefix a trap number with the trap character (†—Option-t) and a trap name with an underscore character (_InitGraf, for example). Use the range operator (..) between trap names or numbers to remove breaks set on a range of traps. Example Unbreak _GetResource #undo break on GetResource trap See also Break - Undef —determines if variable is undefined Syntax Undef ( parameter | variable ) Description Undef determines whether the given SADE parameter or variable has been initialized. If the parameter or variable is initialized, Undef returns 0; if it’s not initialized, Undef returns 1. If you pass an undefined identifier to Undef, an error results. - Undefine —removes definitions Syntax Undefine name ,... Description The Undefine command removes the definition of the specified global SADE variable, procedure, function, or macro. You can supply a list of names to remove multiple definitions. Note that Undefine does not remove local variables defined within SADE procedures or functions. If you want to redefine an item, you don’t need to use Undefine; you can just assign a new value to the existing name using the Define command. Example Proc ControlledProc Printf "%d ", ControllerGlobal End Proc Controller Define global ControllerGlobal Define max := 7 For ControllerGlobal := 1 to max ControlledProc End Undefine ControllerGlobal Undefine ControlledProc End #-- output Controller 2 3 4 5 6 7 ControllerGlobal ### Could not find "ControllerGlobal" as a program symbol ControlledProc ### Could not find "ControlledProc" as a program symbol See also Proc, Func, Macro, Define - Unprotect —removes memory protection Syntax Unprotect all | <address expression> [<number of bytes>] Description The Unprotect command removes write protection from specified memory addresses. The all keyword unprotects all currently protected addresses. <address expression> is any expression which SADE can evaluate as an address, e.g. '&foo', '$1C48D0A', 'EVENTS.MAINEVENTLOOP.(3)', etc. <number of bytes> is an optional value specifying how many bytes to unprotect beginning at that address. The default value for <number of bytes> is 4. Examples #-- removes protection of the variable myVar. Unprotect &myVar sizeof(myVar) See also Protect, List - Untrace —removes tracepoints Syntax Untrace addr ,… or Untrace trap ,... or Untrace trap-range ,... or Untrace all [ traps | addrs ] Description The Untrace command clears the tracepoint at the specified addresses or traps. The all keyword clears all tracepoints within the target program. The all keyword can optionally be followed by the traps or addrs keywords to restrict the command to traps or addresses respectively. Addr is a RAM address or symbolic reference. Trap is a trap name or number. You must prefix a trap number with the trap character (†—Option-t) and a trap name with an underscore character (_InitGraf, for example). Specify trap-range to remove traces on a range of traps. Use the range operator (..) between trap names or numbers. Example Untrace _GetResource #undo trace on _GetResource trap See also Trace - Version —displays SADE version information Syntax Version Description The Version command displays the current SADE version number. - Where —returns symbolic representation of address Syntax Where ( address ) Description Where returns a string containing a symbolic representation of the given address. Example #-- Return the source statement corresponding to the program counter (pc). Where(pc) #-- output DoMenuCommand.(31) See also AddrToSource - While ...End —conditionally repeats commands Syntax While Boolean [ do ] commands End Description The While...End construct provides conditional looping with a test at the beginning of the loop. The enclosed commands are executed as long as Boolean is true. If the condition is false at the outset, the enclosed commands are never executed. The do option is not required. It is provided only for consistency with Pascal usage. As long as the Boolean expression is true, the commands will be executed whether you specify this option or not. While constructs may be nested. Example Define goSmall := 10 While goSmall > -2 do While goSmall > 4 do While goSmall > 7 do Printf " Inner loop - goSmall = %d\n", goSmall goSmall := goSmall -1 End Printf " Middle loop - goSmall = %d\n", goSmall goSmall := goSmall - 1 End Printf "Outer loop - goSmall = %d\n", goSmall goSmall := goSmall - 1 End #-- output Inner loop - goSmall = 10 Inner loop - goSmall = 9 Inner loop - goSmall = 8 Middle loop - goSmall = 7 Middle loop - goSmall = 6 Middle loop - goSmall = 5 Outer loop - goSmall = 4 Outer loop - goSmall = 3 Outer loop - goSmall = 2 Outer loop - goSmall = 1 Outer loop - goSmall = 0 Outer loop - goSmall = -1 See also Leave - WindowSize —set size of zoom and new windows Syntax WindowSize zoom | new [ top, left, bottom, right ] Description The WindowSize command allows you to set the size and position that all newly created windows will take, and to set the size and position a window will take when you click the Zoom box (upper right corner of the window). Specify the location for the four corners of the window (in pixels), in the order: top, left, bottom, right. If you specify new, the coordinates that you specify determine the size and location of newly created windows in SADE. If you specify zoom, the coordinates that you specify determine the size and location of windows in SADE when you press the Zoom box. There is no default; you must specify either zoom or new. Example #-- Specify that new windows will be approximately one inch from the top and one #-- inch from the bottom, and will be about two inches long and three inches #-- wide. (There are approximately 72 pixels per inch on the Macintosh screen.) Windowsize new 72,72,144,216 See also MoveWindow, SizeWindow